home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nspr / prio.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  78KB  |  2,031 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. /*
  39.  * File:     prio.h
  40.  *
  41.  * Description:    PR i/o related stuff, such as file system access, file
  42.  *         i/o, socket i/o, etc.
  43.  */
  44.  
  45. #ifndef prio_h___
  46. #define prio_h___
  47.  
  48. #include "prlong.h"
  49. #include "prtime.h"
  50. #include "prinrval.h"
  51. #include "prinet.h"
  52.  
  53. PR_BEGIN_EXTERN_C
  54.  
  55. /* Typedefs */
  56. typedef struct PRDir            PRDir;
  57. typedef struct PRDirEntry       PRDirEntry;
  58. #ifdef MOZ_UNICODE
  59. typedef struct PRDirUTF16       PRDirUTF16;
  60. typedef struct PRDirEntryUTF16  PRDirEntryUTF16;
  61. #endif /* MOZ_UNICODE */
  62. typedef struct PRFileDesc       PRFileDesc;
  63. typedef struct PRFileInfo       PRFileInfo;
  64. typedef struct PRFileInfo64     PRFileInfo64;
  65. typedef union  PRNetAddr        PRNetAddr;
  66. typedef struct PRIOMethods      PRIOMethods;
  67. typedef struct PRPollDesc       PRPollDesc;
  68. typedef struct PRFilePrivate    PRFilePrivate;
  69. typedef struct PRSendFileData   PRSendFileData;
  70.  
  71. /*
  72. ***************************************************************************
  73. ** The file descriptor.
  74. ** This is the primary structure to represent any active open socket,
  75. ** whether it be a normal file or a network connection. Such objects
  76. ** are stackable (or layerable). Each layer may have its own set of
  77. ** method pointers and context private to that layer. All each layer
  78. ** knows about its neighbors is how to get to their method table.
  79. ***************************************************************************
  80. */
  81.  
  82. typedef PRIntn PRDescIdentity;          /* see: Layering file descriptors */
  83.  
  84. struct PRFileDesc {
  85.     const PRIOMethods *methods;         /* the I/O methods table */
  86.     PRFilePrivate *secret;              /* layer dependent data */
  87.     PRFileDesc *lower, *higher;         /* pointers to adjacent layers */
  88.     void (PR_CALLBACK *dtor)(PRFileDesc *fd);
  89.                                         /* A destructor function for layer */
  90.     PRDescIdentity identity;            /* Identity of this particular layer  */
  91. };
  92.  
  93. /*
  94. ***************************************************************************
  95. ** PRTransmitFileFlags
  96. **
  97. ** Flags for PR_TransmitFile.  Pass PR_TRANSMITFILE_CLOSE_SOCKET to
  98. ** PR_TransmitFile if the connection should be closed after the file
  99. ** is transmitted.
  100. ***************************************************************************
  101. */
  102. typedef enum PRTransmitFileFlags {
  103.     PR_TRANSMITFILE_KEEP_OPEN = 0,    /* socket is left open after file
  104.                                        * is transmitted. */
  105.     PR_TRANSMITFILE_CLOSE_SOCKET = 1  /* socket is closed after file
  106.                                        * is transmitted. */
  107. } PRTransmitFileFlags;
  108.  
  109. /*
  110. **************************************************************************
  111. ** Macros for PRNetAddr
  112. **
  113. ** Address families: PR_AF_INET, PR_AF_INET6, PR_AF_LOCAL
  114. ** IP addresses: PR_INADDR_ANY, PR_INADDR_LOOPBACK, PR_INADDR_BROADCAST
  115. **************************************************************************
  116. */
  117.  
  118. #ifdef WIN32
  119.  
  120. #define PR_AF_INET 2
  121. #define PR_AF_LOCAL 1
  122. #define PR_INADDR_ANY (unsigned long)0x00000000
  123. #define PR_INADDR_LOOPBACK 0x7f000001
  124. #define PR_INADDR_BROADCAST (unsigned long)0xffffffff
  125.  
  126. #else /* WIN32 */
  127.  
  128. #define PR_AF_INET AF_INET
  129. #define PR_AF_LOCAL AF_UNIX
  130. #define PR_INADDR_ANY INADDR_ANY
  131. #define PR_INADDR_LOOPBACK INADDR_LOOPBACK
  132. #define PR_INADDR_BROADCAST INADDR_BROADCAST
  133.  
  134. #endif /* WIN32 */
  135.  
  136. /*
  137. ** Define PR_AF_INET6 in prcpucfg.h with the same
  138. ** value as AF_INET6 on platforms with IPv6 support.
  139. ** Otherwise define it here.
  140. */
  141. #ifndef PR_AF_INET6
  142. #define PR_AF_INET6 100
  143. #endif
  144.  
  145. #ifndef PR_AF_UNSPEC
  146. #define PR_AF_UNSPEC 0
  147. #endif
  148.  
  149. /*
  150. **************************************************************************
  151. ** A network address
  152. **
  153. ** Only Internet Protocol (IPv4 and IPv6) addresses are supported.
  154. ** The address family must always represent IPv4 (AF_INET, probably == 2)
  155. ** or IPv6 (AF_INET6).
  156. **************************************************************************
  157. *************************************************************************/
  158.  
  159. struct PRIPv6Addr {
  160.     union {
  161.         PRUint8  _S6_u8[16];
  162.         PRUint16 _S6_u16[8];
  163.         PRUint32 _S6_u32[4];
  164.         PRUint64 _S6_u64[2];
  165.     } _S6_un;
  166. };
  167. #define pr_s6_addr        _S6_un._S6_u8
  168. #define pr_s6_addr16    _S6_un._S6_u16
  169. #define pr_s6_addr32    _S6_un._S6_u32
  170. #define pr_s6_addr64     _S6_un._S6_u64
  171.  
  172. typedef struct PRIPv6Addr PRIPv6Addr;
  173.  
  174. union PRNetAddr {
  175.     struct {
  176.         PRUint16 family;                /* address family (0x00ff maskable) */
  177. #ifdef XP_BEOS
  178.         char data[10];                  /* Be has a smaller structure */
  179. #else
  180.         char data[14];                  /* raw address data */
  181. #endif
  182.     } raw;
  183.     struct {
  184.         PRUint16 family;                /* address family (AF_INET) */
  185.         PRUint16 port;                  /* port number */
  186.         PRUint32 ip;                    /* The actual 32 bits of address */
  187. #ifdef XP_BEOS
  188.         char pad[4];                    /* Be has a smaller structure */
  189. #else
  190.         char pad[8];
  191. #endif
  192.     } inet;
  193.     struct {
  194.         PRUint16 family;                /* address family (AF_INET6) */
  195.         PRUint16 port;                  /* port number */
  196.         PRUint32 flowinfo;              /* routing information */
  197.         PRIPv6Addr ip;                  /* the actual 128 bits of address */
  198.         PRUint32 scope_id;              /* set of interfaces for a scope */
  199.     } ipv6;
  200. #if defined(XP_UNIX) || defined(XP_OS2_EMX)
  201.     struct {                            /* Unix domain socket address */
  202.         PRUint16 family;                /* address family (AF_UNIX) */
  203. #ifdef XP_OS2
  204.         char path[108];                 /* null-terminated pathname */
  205.                                         /* bind fails if size is not 108. */
  206. #else
  207.         char path[104];                 /* null-terminated pathname */
  208. #endif
  209.     } local;
  210. #endif
  211. };
  212.  
  213. /*
  214. ***************************************************************************
  215. ** PRSockOption
  216. **
  217. ** The file descriptors can have predefined options set after they file
  218. ** descriptor is created to change their behavior. Only the options in
  219. ** the following enumeration are supported.
  220. ***************************************************************************
  221. */
  222. typedef enum PRSockOption
  223. {
  224.     PR_SockOpt_Nonblocking,     /* nonblocking io */
  225.     PR_SockOpt_Linger,          /* linger on close if data present */
  226.     PR_SockOpt_Reuseaddr,       /* allow local address reuse */
  227.     PR_SockOpt_Keepalive,       /* keep connections alive */
  228.     PR_SockOpt_RecvBufferSize,  /* send buffer size */
  229.     PR_SockOpt_SendBufferSize,  /* receive buffer size */
  230.  
  231.     PR_SockOpt_IpTimeToLive,    /* time to live */
  232.     PR_SockOpt_IpTypeOfService, /* type of service and precedence */
  233.  
  234.     PR_SockOpt_AddMember,       /* add an IP group membership */
  235.     PR_SockOpt_DropMember,      /* drop an IP group membership */
  236.     PR_SockOpt_McastInterface,  /* multicast interface address */
  237.     PR_SockOpt_McastTimeToLive, /* multicast timetolive */
  238.     PR_SockOpt_McastLoopback,   /* multicast loopback */
  239.  
  240.     PR_SockOpt_NoDelay,         /* don't delay send to coalesce packets */
  241.     PR_SockOpt_MaxSegment,      /* maximum segment size */
  242.     PR_SockOpt_Broadcast,       /* enable broadcast */
  243.     PR_SockOpt_Last
  244. } PRSockOption;
  245.  
  246. typedef struct PRLinger {
  247.     PRBool polarity;            /* Polarity of the option's setting */
  248.     PRIntervalTime linger;        /* Time to linger before closing */
  249. } PRLinger;
  250.  
  251. typedef struct PRMcastRequest {
  252.     PRNetAddr mcaddr;            /* IP multicast address of group */
  253.     PRNetAddr ifaddr;            /* local IP address of interface */
  254. } PRMcastRequest;
  255.  
  256. typedef struct PRSocketOptionData
  257. {
  258.     PRSockOption option;
  259.     union
  260.     {
  261.         PRUintn ip_ttl;             /* IP time to live */
  262.         PRUintn mcast_ttl;          /* IP multicast time to live */
  263.         PRUintn tos;                /* IP type of service and precedence */
  264.         PRBool non_blocking;        /* Non-blocking (network) I/O */
  265.         PRBool reuse_addr;          /* Allow local address reuse */
  266.         PRBool keep_alive;          /* Keep connections alive */
  267.         PRBool mcast_loopback;      /* IP multicast loopback */
  268.         PRBool no_delay;            /* Don't delay send to coalesce packets */
  269.         PRBool broadcast;           /* Enable broadcast */
  270.         PRSize max_segment;         /* Maximum segment size */
  271.         PRSize recv_buffer_size;    /* Receive buffer size */
  272.         PRSize send_buffer_size;    /* Send buffer size */
  273.         PRLinger linger;            /* Time to linger on close if data present */
  274.         PRMcastRequest add_member;  /* add an IP group membership */
  275.         PRMcastRequest drop_member; /* Drop an IP group membership */
  276.         PRNetAddr mcast_if;         /* multicast interface address */
  277.     } value;
  278. } PRSocketOptionData;
  279.  
  280. /*
  281. ***************************************************************************
  282. ** PRIOVec
  283. **
  284. ** The I/O vector is used by the write vector method to describe the areas
  285. ** that are affected by the ouput operation.
  286. ***************************************************************************
  287. */
  288. typedef struct PRIOVec {
  289.     char *iov_base;
  290.     int iov_len;
  291. } PRIOVec;
  292.  
  293. /*
  294. ***************************************************************************
  295. ** Discover what type of socket is being described by the file descriptor.
  296. ***************************************************************************
  297. */
  298. typedef enum PRDescType
  299. {
  300.     PR_DESC_FILE = 1,
  301.     PR_DESC_SOCKET_TCP = 2,
  302.     PR_DESC_SOCKET_UDP = 3,
  303.     PR_DESC_LAYERED = 4,
  304.     PR_DESC_PIPE = 5
  305. } PRDescType;
  306.  
  307. typedef enum PRSeekWhence {
  308.     PR_SEEK_SET = 0,
  309.     PR_SEEK_CUR = 1,
  310.     PR_SEEK_END = 2
  311. } PRSeekWhence;
  312.  
  313. NSPR_API(PRDescType) PR_GetDescType(PRFileDesc *file);
  314.  
  315. /*
  316. ***************************************************************************
  317. ** PRIOMethods
  318. **
  319. ** The I/O methods table provides procedural access to the functions of
  320. ** the file descriptor. It is the responsibility of a layer implementor
  321. ** to provide suitable functions at every entry point. If a layer provides
  322. ** no functionality, it should call the next lower(higher) function of the
  323. ** same name (e.g., return fd->lower->method->close(fd->lower));
  324. **
  325. ** Not all functions are implemented for all types of files. In cases where
  326. ** that is true, the function will return a error indication with an error
  327. ** code of PR_INVALID_METHOD_ERROR.
  328. ***************************************************************************
  329. */
  330.  
  331. typedef PRStatus (PR_CALLBACK *PRCloseFN)(PRFileDesc *fd);
  332. typedef PRInt32 (PR_CALLBACK *PRReadFN)(PRFileDesc *fd, void *buf, PRInt32 amount);
  333. typedef PRInt32 (PR_CALLBACK *PRWriteFN)(PRFileDesc *fd, const void *buf, PRInt32 amount);
  334. typedef PRInt32 (PR_CALLBACK *PRAvailableFN)(PRFileDesc *fd);
  335. typedef PRInt64 (PR_CALLBACK *PRAvailable64FN)(PRFileDesc *fd);
  336. typedef PRStatus (PR_CALLBACK *PRFsyncFN)(PRFileDesc *fd);
  337. typedef PROffset32 (PR_CALLBACK *PRSeekFN)(PRFileDesc *fd, PROffset32 offset, PRSeekWhence how);
  338. typedef PROffset64 (PR_CALLBACK *PRSeek64FN)(PRFileDesc *fd, PROffset64 offset, PRSeekWhence how);
  339. typedef PRStatus (PR_CALLBACK *PRFileInfoFN)(PRFileDesc *fd, PRFileInfo *info);
  340. typedef PRStatus (PR_CALLBACK *PRFileInfo64FN)(PRFileDesc *fd, PRFileInfo64 *info);
  341. typedef PRInt32 (PR_CALLBACK *PRWritevFN)(
  342.     PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
  343.     PRIntervalTime timeout);
  344. typedef PRStatus (PR_CALLBACK *PRConnectFN)(
  345.     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
  346. typedef PRFileDesc* (PR_CALLBACK *PRAcceptFN) (
  347.     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
  348. typedef PRStatus (PR_CALLBACK *PRBindFN)(PRFileDesc *fd, const PRNetAddr *addr);
  349. typedef PRStatus (PR_CALLBACK *PRListenFN)(PRFileDesc *fd, PRIntn backlog);
  350. typedef PRStatus (PR_CALLBACK *PRShutdownFN)(PRFileDesc *fd, PRIntn how);
  351. typedef PRInt32 (PR_CALLBACK *PRRecvFN)(
  352.     PRFileDesc *fd, void *buf, PRInt32 amount,
  353.     PRIntn flags, PRIntervalTime timeout);
  354. typedef PRInt32 (PR_CALLBACK *PRSendFN) (
  355.     PRFileDesc *fd, const void *buf, PRInt32 amount,
  356.     PRIntn flags, PRIntervalTime timeout);
  357. typedef PRInt32 (PR_CALLBACK *PRRecvfromFN)(
  358.     PRFileDesc *fd, void *buf, PRInt32 amount,
  359.     PRIntn flags, PRNetAddr *addr, PRIntervalTime timeout);
  360. typedef PRInt32 (PR_CALLBACK *PRSendtoFN)(
  361.     PRFileDesc *fd, const void *buf, PRInt32 amount,
  362.     PRIntn flags, const PRNetAddr *addr, PRIntervalTime timeout);
  363. typedef PRInt16 (PR_CALLBACK *PRPollFN)(
  364.     PRFileDesc *fd, PRInt16 in_flags, PRInt16 *out_flags);
  365. typedef PRInt32 (PR_CALLBACK *PRAcceptreadFN)(
  366.     PRFileDesc *sd, PRFileDesc **nd, PRNetAddr **raddr,
  367.     void *buf, PRInt32 amount, PRIntervalTime t);
  368. typedef PRInt32 (PR_CALLBACK *PRTransmitfileFN)(
  369.      PRFileDesc *sd, PRFileDesc *fd, const void *headers,
  370.      PRInt32 hlen, PRTransmitFileFlags flags, PRIntervalTime t);
  371. typedef PRStatus (PR_CALLBACK *PRGetsocknameFN)(PRFileDesc *fd, PRNetAddr *addr);
  372. typedef PRStatus (PR_CALLBACK *PRGetpeernameFN)(PRFileDesc *fd, PRNetAddr *addr);
  373. typedef PRStatus (PR_CALLBACK *PRGetsocketoptionFN)(
  374.     PRFileDesc *fd, PRSocketOptionData *data);
  375. typedef PRStatus (PR_CALLBACK *PRSetsocketoptionFN)(
  376.     PRFileDesc *fd, const PRSocketOptionData *data);
  377. typedef PRInt32 (PR_CALLBACK *PRSendfileFN)(
  378.     PRFileDesc *networkSocket, PRSendFileData *sendData,
  379.     PRTransmitFileFlags flags, PRIntervalTime timeout);
  380. typedef PRStatus (PR_CALLBACK *PRConnectcontinueFN)(
  381.     PRFileDesc *fd, PRInt16 out_flags);
  382. typedef PRIntn (PR_CALLBACK *PRReservedFN)(PRFileDesc *fd);
  383.  
  384. struct PRIOMethods {
  385.     PRDescType file_type;           /* Type of file represented (tos)           */
  386.     PRCloseFN close;                /* close file and destroy descriptor        */
  387.     PRReadFN read;                  /* read up to specified bytes into buffer   */
  388.     PRWriteFN write;                /* write specified bytes from buffer        */
  389.     PRAvailableFN available;        /* determine number of bytes available      */
  390.     PRAvailable64FN available64;    /*          ditto, 64 bit                   */
  391.     PRFsyncFN fsync;                /* flush all buffers to permanent store     */
  392.     PRSeekFN seek;                  /* position the file to the desired place   */
  393.     PRSeek64FN seek64;              /*           ditto, 64 bit                  */
  394.     PRFileInfoFN fileInfo;          /* Get information about an open file       */
  395.     PRFileInfo64FN fileInfo64;      /*           ditto, 64 bit                  */
  396.     PRWritevFN writev;              /* Write segments as described by iovector  */
  397.     PRConnectFN connect;            /* Connect to the specified (net) address   */
  398.     PRAcceptFN accept;              /* Accept a connection for a (net) peer     */
  399.     PRBindFN bind;                  /* Associate a (net) address with the fd    */
  400.     PRListenFN listen;              /* Prepare to listen for (net) connections  */
  401.     PRShutdownFN shutdown;          /* Shutdown a (net) connection              */
  402.     PRRecvFN recv;                  /* Solicit up the the specified bytes       */
  403.     PRSendFN send;                  /* Send all the bytes specified             */
  404.     PRRecvfromFN recvfrom;          /* Solicit (net) bytes and report source    */
  405.     PRSendtoFN sendto;              /* Send bytes to (net) address specified    */
  406.     PRPollFN poll;                  /* Test the fd to see if it is ready        */
  407.     PRAcceptreadFN acceptread;      /* Accept and read on a new (net) fd        */
  408.     PRTransmitfileFN transmitfile;  /* Transmit at entire file                  */
  409.     PRGetsocknameFN getsockname;    /* Get (net) address associated with fd     */
  410.     PRGetpeernameFN getpeername;    /* Get peer's (net) address                 */
  411.     PRReservedFN reserved_fn_6;     /* reserved for future use */
  412.     PRReservedFN reserved_fn_5;     /* reserved for future use */
  413.     PRGetsocketoptionFN getsocketoption;
  414.                                     /* Get current setting of specified option  */
  415.     PRSetsocketoptionFN setsocketoption;
  416.                                     /* Set value of specified option            */
  417.     PRSendfileFN sendfile;            /* Send a (partial) file with header/trailer*/
  418.     PRConnectcontinueFN connectcontinue;
  419.                                     /* Continue a nonblocking connect */
  420.     PRReservedFN reserved_fn_3;        /* reserved for future use */
  421.     PRReservedFN reserved_fn_2;        /* reserved for future use */
  422.     PRReservedFN reserved_fn_1;        /* reserved for future use */
  423.     PRReservedFN reserved_fn_0;        /* reserved for future use */
  424. };
  425.  
  426. /*
  427.  **************************************************************************
  428.  * FUNCTION: PR_GetSpecialFD
  429.  * DESCRIPTION: Get the file descriptor that represents the standard input,
  430.  *              output, or error stream.
  431.  * INPUTS:
  432.  *     PRSpecialFD id
  433.  *         A value indicating the type of stream desired:
  434.  *             PR_StandardInput: standard input
  435.  *             PR_StandardOuput: standard output
  436.  *             PR_StandardError: standard error
  437.  * OUTPUTS: none
  438.  * RETURNS: PRFileDesc *
  439.  *     If the argument is valid, PR_GetSpecialFD returns a file descriptor
  440.  *     that represents the corresponding standard I/O stream.  Otherwise,
  441.  *     PR_GetSpecialFD returns NULL and sets error PR_INVALID_ARGUMENT_ERROR.
  442.  **************************************************************************
  443.  */
  444.  
  445. typedef enum PRSpecialFD
  446. {
  447.     PR_StandardInput,          /* standard input */
  448.     PR_StandardOutput,         /* standard output */
  449.     PR_StandardError           /* standard error */
  450. } PRSpecialFD;
  451.  
  452. NSPR_API(PRFileDesc*) PR_GetSpecialFD(PRSpecialFD id);
  453.  
  454. #define PR_STDIN    PR_GetSpecialFD(PR_StandardInput)
  455. #define PR_STDOUT    PR_GetSpecialFD(PR_StandardOutput)
  456. #define PR_STDERR    PR_GetSpecialFD(PR_StandardError)
  457.  
  458. /*
  459.  **************************************************************************
  460.  * Layering file descriptors
  461.  *
  462.  * File descriptors may be layered. Each layer has it's own identity.
  463.  * Identities are allocated by the runtime and are to be associated
  464.  * (by the layer implementor) with all layers that are of that type.
  465.  * It is then possible to scan the chain of layers and find a layer
  466.  * that one recongizes and therefore predict that it will implement
  467.  * a desired protocol.
  468.  *
  469.  * There are three well-known identities:
  470.  *      PR_INVALID_IO_LAYER => an invalid layer identity, for error return
  471.  *      PR_TOP_IO_LAYER     => the identity of the top of the stack
  472.  *      PR_NSPR_IO_LAYER    => the identity used by NSPR proper
  473.  * PR_TOP_IO_LAYER may be used as a shorthand for identifying the topmost
  474.  * layer of an existing stack. Ie., the following two constructs are
  475.  * equivalent.
  476.  *
  477.  *      rv = PR_PushIOLayer(stack, PR_TOP_IO_LAYER, my_layer);
  478.  *      rv = PR_PushIOLayer(stack, PR_GetLayersIdentity(stack), my_layer)
  479.  *
  480.  * A string may be associated with the creation of the identity. It
  481.  * will be copied by the runtime. If queried the runtime will return
  482.  * a reference to that copied string (not yet another copy). There
  483.  * is no facility for deleting an identity.
  484.  **************************************************************************
  485.  */
  486.  
  487. #define PR_IO_LAYER_HEAD (PRDescIdentity)-3
  488. #define PR_INVALID_IO_LAYER (PRDescIdentity)-1
  489. #define PR_TOP_IO_LAYER (PRDescIdentity)-2
  490. #define PR_NSPR_IO_LAYER (PRDescIdentity)0
  491.  
  492. NSPR_API(PRDescIdentity) PR_GetUniqueIdentity(const char *layer_name);
  493. NSPR_API(const char*) PR_GetNameForIdentity(PRDescIdentity ident);
  494. NSPR_API(PRDescIdentity) PR_GetLayersIdentity(PRFileDesc* fd);
  495. NSPR_API(PRFileDesc*) PR_GetIdentitiesLayer(PRFileDesc* fd_stack, PRDescIdentity id);
  496.  
  497. /*
  498.  **************************************************************************
  499.  * PR_GetDefaultIOMethods: Accessing the default methods table.
  500.  * You may get a pointer to the default methods table by calling this function.
  501.  * You may then select any elements from that table with which to build your
  502.  * layer's methods table. You may NOT modify the table directly.
  503.  **************************************************************************
  504.  */
  505. NSPR_API(const PRIOMethods *) PR_GetDefaultIOMethods(void);
  506.  
  507. /*
  508.  **************************************************************************
  509.  * Creating a layer
  510.  *
  511.  * A new layer may be allocated by calling PR_CreateIOLayerStub(). The
  512.  * file descriptor returned will contain the pointer to the methods table
  513.  * provided. The runtime will not modify the table nor test its correctness.
  514.  **************************************************************************
  515.  */
  516. NSPR_API(PRFileDesc*) PR_CreateIOLayerStub(
  517.     PRDescIdentity ident, const PRIOMethods *methods);
  518.  
  519. /*
  520.  **************************************************************************
  521.  * Creating a layer
  522.  *
  523.  * A new stack may be created by calling PR_CreateIOLayer(). The
  524.  * file descriptor returned will point to the top of the stack, which has
  525.  * the layer 'fd' as the topmost layer.
  526.  * 
  527.  * NOTE: This function creates a new style stack, which has a fixed, dummy
  528.  * header. The old style stack, created by a call to PR_PushIOLayer,
  529.  * results in modifying contents of the top layer of the stack, when
  530.  * pushing and popping layers of the stack.
  531.  **************************************************************************
  532.  */
  533. NSPR_API(PRFileDesc*) PR_CreateIOLayer(PRFileDesc* fd);
  534.  
  535. /*
  536.  **************************************************************************
  537.  * Pushing a layer
  538.  *
  539.  * A file descriptor (perhaps allocated using PR_CreateIOLayerStub()) may
  540.  * be pushed into an existing stack of file descriptors at any point the
  541.  * caller deems appropriate. The new layer will be inserted into the stack
  542.  * just above the layer with the indicated identity.
  543.  *
  544.  * Note: Even if the identity parameter indicates the top-most layer of
  545.  * the stack, the value of the file descriptor describing the original
  546.  * stack will not change.
  547.  **************************************************************************
  548.  */
  549. NSPR_API(PRStatus) PR_PushIOLayer(
  550.     PRFileDesc *fd_stack, PRDescIdentity id, PRFileDesc *layer);
  551.  
  552. /*
  553.  **************************************************************************
  554.  * Popping a layer
  555.  *
  556.  * A layer may be popped from a stack by indicating the identity of the
  557.  * layer to be removed. If found, a pointer to the removed object will
  558.  * be returned to the caller. The object then becomes the responsibility
  559.  * of the caller.
  560.  *
  561.  * Note: Even if the identity indicates the top layer of the stack, the
  562.  * reference returned will not be the file descriptor for the stack and
  563.  * that file descriptor will remain valid.
  564.  **************************************************************************
  565.  */
  566. NSPR_API(PRFileDesc*) PR_PopIOLayer(PRFileDesc *fd_stack, PRDescIdentity id);
  567.  
  568. /*
  569.  **************************************************************************
  570.  * FUNCTION:    PR_Open
  571.  * DESCRIPTION:    Open a file for reading, writing, or both.
  572.  * INPUTS:
  573.  *     const char *name
  574.  *         The path name of the file to be opened
  575.  *     PRIntn flags
  576.  *         The file status flags.
  577.  *         It is a bitwise OR of the following bit flags (only one of
  578.  *         the first three flags below may be used):
  579.  *        PR_RDONLY        Open for reading only.
  580.  *        PR_WRONLY        Open for writing only.
  581.  *        PR_RDWR          Open for reading and writing.
  582.  *        PR_CREATE_FILE   If the file does not exist, the file is created
  583.  *                              If the file exists, this flag has no effect.
  584.  *      PR_SYNC          If set, each write will wait for both the file data
  585.  *                              and file status to be physically updated.
  586.  *        PR_APPEND        The file pointer is set to the end of
  587.  *                              the file prior to each write.
  588.  *        PR_TRUNCATE      If the file exists, its length is truncated to 0.
  589.  *      PR_EXCL          With PR_CREATE_FILE, if the file does not exist,
  590.  *                              the file is created. If the file already 
  591.  *                              exists, no action and NULL is returned
  592.  *
  593.  *     PRIntn mode
  594.  *         The access permission bits of the file mode, if the file is
  595.  *         created when PR_CREATE_FILE is on.
  596.  * OUTPUTS:    None
  597.  * RETURNS:    PRFileDesc *
  598.  *     If the file is successfully opened,
  599.  *     returns a pointer to the PRFileDesc
  600.  *     created for the newly opened file.
  601.  *     Returns a NULL pointer if the open
  602.  *     failed.
  603.  * SIDE EFFECTS:
  604.  * RESTRICTIONS:
  605.  * MEMORY:
  606.  *     The return value, if not NULL, points to a dynamically allocated
  607.  *     PRFileDesc object.
  608.  * ALGORITHM:
  609.  **************************************************************************
  610.  */
  611.  
  612. /* Open flags */
  613. #define PR_RDONLY       0x01
  614. #define PR_WRONLY       0x02
  615. #define PR_RDWR         0x04
  616. #define PR_CREATE_FILE  0x08
  617. #define PR_APPEND       0x10
  618. #define PR_TRUNCATE     0x20
  619. #define PR_SYNC         0x40
  620. #define PR_EXCL         0x80
  621.  
  622. /*
  623. ** File modes ....
  624. **
  625. ** CAVEAT: 'mode' is currently only applicable on UNIX platforms.
  626. ** The 'mode' argument may be ignored by PR_Open on other platforms.
  627. **
  628. **   00400   Read by owner.
  629. **   00200   Write by owner.
  630. **   00100   Execute (search if a directory) by owner.
  631. **   00040   Read by group.
  632. **   00020   Write by group.
  633. **   00010   Execute by group.
  634. **   00004   Read by others.
  635. **   00002   Write by others
  636. **   00001   Execute by others.
  637. **
  638. */
  639.  
  640. NSPR_API(PRFileDesc*) PR_Open(const char *name, PRIntn flags, PRIntn mode);
  641.  
  642. /*
  643.  **************************************************************************
  644.  * FUNCTION: PR_OpenFile
  645.  * DESCRIPTION:
  646.  *     Open a file for reading, writing, or both.
  647.  *     PR_OpenFile has the same prototype as PR_Open but implements
  648.  *     the specified file mode where possible.
  649.  **************************************************************************
  650.  */
  651.  
  652. /* File mode bits */
  653. #define PR_IRWXU 00700  /* read, write, execute/search by owner */
  654. #define PR_IRUSR 00400  /* read permission, owner */
  655. #define PR_IWUSR 00200  /* write permission, owner */
  656. #define PR_IXUSR 00100  /* execute/search permission, owner */
  657. #define PR_IRWXG 00070  /* read, write, execute/search by group */
  658. #define PR_IRGRP 00040  /* read permission, group */
  659. #define PR_IWGRP 00020  /* write permission, group */
  660. #define PR_IXGRP 00010  /* execute/search permission, group */
  661. #define PR_IRWXO 00007  /* read, write, execute/search by others */
  662. #define PR_IROTH 00004  /* read permission, others */
  663. #define PR_IWOTH 00002  /* write permission, others */
  664. #define PR_IXOTH 00001  /* execute/search permission, others */
  665.  
  666. NSPR_API(PRFileDesc*) PR_OpenFile(
  667.     const char *name, PRIntn flags, PRIntn mode);
  668.  
  669. #ifdef MOZ_UNICODE
  670. /*
  671.  * EXPERIMENTAL: This function may be removed in a future release.
  672.  */
  673. NSPR_API(PRFileDesc*) PR_OpenFileUTF16(
  674.     const PRUnichar *name, PRIntn flags, PRIntn mode);
  675. #endif /* MOZ_UNICODE */
  676.  
  677. /*
  678.  **************************************************************************
  679.  * FUNCTION: PR_Close
  680.  * DESCRIPTION:
  681.  *     Close a file or socket.
  682.  * INPUTS:
  683.  *     PRFileDesc *fd
  684.  *         a pointer to a PRFileDesc.
  685.  * OUTPUTS:
  686.  *     None.
  687.  * RETURN:
  688.  *     PRStatus
  689.  * SIDE EFFECTS:
  690.  * RESTRICTIONS:
  691.  *     None.
  692.  * MEMORY:
  693.  *     The dynamic memory pointed to by the argument fd is freed.
  694.  **************************************************************************
  695.  */
  696.  
  697. NSPR_API(PRStatus)    PR_Close(PRFileDesc *fd);
  698.  
  699. /*
  700.  **************************************************************************
  701.  * FUNCTION: PR_Read
  702.  * DESCRIPTION:
  703.  *     Read bytes from a file or socket.
  704.  *     The operation will block until either an end of stream indication is
  705.  *     encountered, some positive number of bytes are transferred, or there
  706.  *     is an error. No more than 'amount' bytes will be transferred.
  707.  * INPUTS:
  708.  *     PRFileDesc *fd
  709.  *         pointer to the PRFileDesc object for the file or socket
  710.  *     void *buf
  711.  *         pointer to a buffer to hold the data read in.
  712.  *     PRInt32 amount
  713.  *         the size of 'buf' (in bytes)
  714.  * OUTPUTS:
  715.  * RETURN:
  716.  *     PRInt32
  717.  *         a positive number indicates the number of bytes actually read in.
  718.  *         0 means end of file is reached or the network connection is closed.
  719.  *         -1 indicates a failure. The reason for the failure is obtained
  720.  *         by calling PR_GetError().
  721.  * SIDE EFFECTS:
  722.  *     data is written into the buffer pointed to by 'buf'.
  723.  * RESTRICTIONS:
  724.  *     None.
  725.  * MEMORY:
  726.  *     N/A
  727.  * ALGORITHM:
  728.  *     N/A
  729.  **************************************************************************
  730.  */
  731.  
  732. NSPR_API(PRInt32) PR_Read(PRFileDesc *fd, void *buf, PRInt32 amount);
  733.  
  734. /*
  735.  ***************************************************************************
  736.  * FUNCTION: PR_Write
  737.  * DESCRIPTION:
  738.  *     Write a specified number of bytes to a file or socket.  The thread
  739.  *     invoking this function blocks until all the data is written.
  740.  * INPUTS:
  741.  *     PRFileDesc *fd
  742.  *         pointer to a PRFileDesc object that refers to a file or socket
  743.  *     const void *buf
  744.  *         pointer to the buffer holding the data
  745.  *     PRInt32 amount
  746.  *         amount of data in bytes to be written from the buffer
  747.  * OUTPUTS:
  748.  *     None.
  749.  * RETURN: PRInt32
  750.  *     A positive number indicates the number of bytes successfully written.
  751.  *     A -1 is an indication that the operation failed. The reason
  752.  *     for the failure is obtained by calling PR_GetError().
  753.  ***************************************************************************
  754.  */
  755.  
  756. NSPR_API(PRInt32) PR_Write(PRFileDesc *fd,const void *buf,PRInt32 amount);
  757.  
  758. /*
  759.  ***************************************************************************
  760.  * FUNCTION: PR_Writev
  761.  * DESCRIPTION:
  762.  *     Write data to a socket.  The data is organized in a PRIOVec array. The
  763.  *     operation will block until all the data is written or the operation
  764.  *     fails.
  765.  * INPUTS:
  766.  *     PRFileDesc *fd
  767.  *         Pointer that points to a PRFileDesc object for a socket.
  768.  *     const PRIOVec *iov
  769.  *         An array of PRIOVec.  PRIOVec is a struct with the following
  770.  *         two fields:
  771.  *             char *iov_base;
  772.  *             int iov_len;
  773.  *     PRInt32 iov_size
  774.  *         Number of elements in the iov array. The value of this
  775.  *         argument must not be greater than PR_MAX_IOVECTOR_SIZE.
  776.  *         If it is, the method will fail (PR_BUFFER_OVERFLOW_ERROR).
  777.  *     PRIntervalTime timeout
  778.  *       Time limit for completion of the entire write operation.
  779.  * OUTPUTS:
  780.  *     None
  781.  * RETURN:
  782.  *     A positive number indicates the number of bytes successfully written.
  783.  *     A -1 is an indication that the operation failed. The reason
  784.  *     for the failure is obtained by calling PR_GetError().
  785.  ***************************************************************************
  786.  */
  787.  
  788. #define PR_MAX_IOVECTOR_SIZE 16   /* 'iov_size' must be <= */
  789.  
  790. NSPR_API(PRInt32) PR_Writev(
  791.     PRFileDesc *fd, const PRIOVec *iov, PRInt32 iov_size,
  792.     PRIntervalTime timeout);
  793.  
  794. /*
  795.  ***************************************************************************
  796.  * FUNCTION: PR_Delete
  797.  * DESCRIPTION:
  798.  *     Delete a file from the filesystem. The operation may fail if the
  799.  *     file is open.
  800.  * INPUTS:
  801.  *     const char *name
  802.  *         Path name of the file to be deleted.
  803.  * OUTPUTS:
  804.  *     None.
  805.  * RETURN: PRStatus
  806.  *     The function returns PR_SUCCESS if the file is successfully
  807.  *     deleted, otherwise it returns PR_FAILURE.
  808.  ***************************************************************************
  809.  */
  810.  
  811. NSPR_API(PRStatus) PR_Delete(const char *name);
  812.  
  813. /**************************************************************************/
  814.  
  815. typedef enum PRFileType
  816. {
  817.     PR_FILE_FILE = 1,
  818.     PR_FILE_DIRECTORY = 2,
  819.     PR_FILE_OTHER = 3
  820. } PRFileType;
  821.  
  822. struct PRFileInfo {
  823.     PRFileType type;        /* Type of file */
  824.     PROffset32 size;        /* Size, in bytes, of file's contents */
  825.     PRTime creationTime;    /* Creation time per definition of PRTime */
  826.     PRTime modifyTime;      /* Last modification time per definition of PRTime */
  827. };
  828.  
  829. struct PRFileInfo64 {
  830.     PRFileType type;        /* Type of file */
  831.     PROffset64 size;        /* Size, in bytes, of file's contents */
  832.     PRTime creationTime;    /* Creation time per definition of PRTime */
  833.     PRTime modifyTime;      /* Last modification time per definition of PRTime */
  834. };
  835.  
  836. /****************************************************************************
  837.  * FUNCTION: PR_GetFileInfo, PR_GetFileInfo64
  838.  * DESCRIPTION:
  839.  *     Get the information about the file with the given path name. This is
  840.  *     applicable only to NSFileDesc describing 'file' types (see
  841.  * INPUTS:
  842.  *     const char *fn
  843.  *         path name of the file
  844.  * OUTPUTS:
  845.  *     PRFileInfo *info
  846.  *         Information about the given file is written into the file
  847.  *         information object pointer to by 'info'.
  848.  * RETURN: PRStatus
  849.  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  850.  *     obtained, otherwise it returns PR_FAILURE.
  851.  ***************************************************************************
  852.  */
  853.  
  854. NSPR_API(PRStatus) PR_GetFileInfo(const char *fn, PRFileInfo *info);
  855. NSPR_API(PRStatus) PR_GetFileInfo64(const char *fn, PRFileInfo64 *info);
  856.  
  857. #ifdef MOZ_UNICODE
  858. /*
  859.  * EXPERIMENTAL: This function may be removed in a future release.
  860.  */
  861. NSPR_API(PRStatus) PR_GetFileInfo64UTF16(const PRUnichar *fn, PRFileInfo64 *info);
  862. #endif /* MOZ_UNICODE */
  863.  
  864. /*
  865.  **************************************************************************
  866.  * FUNCTION: PR_GetOpenFileInfo, PR_GetOpenFileInfo64
  867.  * DESCRIPTION:
  868.  *     Get information about an open file referred to by the
  869.  *     given PRFileDesc object.
  870.  * INPUTS:
  871.  *     const PRFileDesc *fd
  872.  *          A reference to a valid, open file.
  873.  * OUTPUTS:
  874.  *     Same as PR_GetFileInfo, PR_GetFileInfo64
  875.  * RETURN: PRStatus
  876.  *     PR_GetFileInfo returns PR_SUCCESS if file information is successfully
  877.  *     obtained, otherwise it returns PR_FAILURE.
  878.  ***************************************************************************
  879.  */
  880.  
  881. NSPR_API(PRStatus) PR_GetOpenFileInfo(PRFileDesc *fd, PRFileInfo *info);
  882. NSPR_API(PRStatus) PR_GetOpenFileInfo64(PRFileDesc *fd, PRFileInfo64 *info);
  883.  
  884. /*
  885.  **************************************************************************
  886.  * FUNCTION: PR_Rename
  887.  * DESCRIPTION:
  888.  *     Rename a file from the old name 'from' to the new name 'to'.
  889.  * INPUTS:
  890.  *     const char *from
  891.  *         The old name of the file to be renamed.
  892.  *     const char *to
  893.  *         The new name of the file.
  894.  * OUTPUTS:
  895.  *     None.
  896.  * RETURN: PRStatus
  897.  **************************************************************************
  898.  */
  899.  
  900. NSPR_API(PRStatus)    PR_Rename(const char *from, const char *to);
  901.  
  902. /*
  903.  *************************************************************************
  904.  * FUNCTION: PR_Access
  905.  * DESCRIPTION:
  906.  *     Determine accessibility of a file.
  907.  * INPUTS:
  908.  *     const char *name
  909.  *         path name of the file
  910.  *     PRAccessHow how
  911.  *         specifies which access permission to check for.
  912.  *         It can be one of the following values:
  913.  *             PR_ACCESS_READ_OK       Test for read permission
  914.  *             PR_ACCESS_WRITE_OK      Test for write permission
  915.  *             PR_ACCESS_EXISTS        Check existence of file
  916.  * OUTPUTS:
  917.  *     None.
  918.  * RETURN: PRStatus
  919.  *     PR_SUCCESS is returned if the requested access is permitted.
  920.  *     Otherwise, PR_FAILURE is returned. Additional information
  921.  *     regarding the reason for the failure may be retrieved from
  922.  *     PR_GetError().
  923.  *************************************************************************
  924.  */
  925.  
  926. typedef enum PRAccessHow {
  927.     PR_ACCESS_EXISTS = 1,
  928.     PR_ACCESS_WRITE_OK = 2,
  929.     PR_ACCESS_READ_OK = 3
  930. } PRAccessHow;
  931.  
  932. NSPR_API(PRStatus) PR_Access(const char *name, PRAccessHow how);
  933.  
  934. /*
  935.  *************************************************************************
  936.  * FUNCTION: PR_Seek, PR_Seek64
  937.  * DESCRIPTION:
  938.  *     Moves read-write file offset
  939.  * INPUTS:
  940.  *     PRFileDesc *fd
  941.  *         Pointer to a PRFileDesc object.
  942.  *     PROffset32, PROffset64 offset
  943.  *         Specifies a value, in bytes, that is used in conjunction
  944.  *         with the 'whence' parameter to set the file pointer.  A
  945.  *         negative value causes seeking in the reverse direction.
  946.  *     PRSeekWhence whence
  947.  *         Specifies how to interpret the 'offset' parameter in setting
  948.  *         the file pointer associated with the 'fd' parameter.
  949.  *         Values for the 'whence' parameter are:
  950.  *             PR_SEEK_SET  Sets the file pointer to the value of the
  951.  *                          'offset' parameter
  952.  *             PR_SEEK_CUR  Sets the file pointer to its current location
  953.  *                          plus the value of the offset parameter.
  954.  *             PR_SEEK_END  Sets the file pointer to the size of the
  955.  *                          file plus the value of the offset parameter.
  956.  * OUTPUTS:
  957.  *     None.
  958.  * RETURN: PROffset32, PROffset64
  959.  *     Upon successful completion, the resulting pointer location,
  960.  *     measured in bytes from the beginning of the file, is returned.
  961.  *     If the PR_Seek() function fails, the file offset remains
  962.  *     unchanged, and the returned value is -1. The error code can
  963.  *     then be retrieved via PR_GetError().
  964.  *************************************************************************
  965.  */
  966.  
  967. NSPR_API(PROffset32) PR_Seek(PRFileDesc *fd, PROffset32 offset, PRSeekWhence whence);
  968. NSPR_API(PROffset64) PR_Seek64(PRFileDesc *fd, PROffset64 offset, PRSeekWhence whence);
  969.  
  970. /*
  971.  ************************************************************************
  972.  * FUNCTION: PR_Available
  973.  * DESCRIPTION:
  974.  *     Determine the amount of data in bytes available for reading
  975.  *     in the given file or socket.
  976.  * INPUTS:
  977.  *     PRFileDesc *fd
  978.  *         Pointer to a PRFileDesc object that refers to a file or
  979.  *         socket.
  980.  * OUTPUTS:
  981.  *     None
  982.  * RETURN: PRInt32, PRInt64
  983.  *     Upon successful completion, PR_Available returns the number of
  984.  *     bytes beyond the current read pointer that is available for
  985.  *     reading.  Otherwise, it returns a -1 and the reason for the
  986.  *     failure can be retrieved via PR_GetError().
  987.  ************************************************************************
  988.  */
  989.  
  990. NSPR_API(PRInt32) PR_Available(PRFileDesc *fd);
  991. NSPR_API(PRInt64) PR_Available64(PRFileDesc *fd);
  992.  
  993. /*
  994.  ************************************************************************
  995.  * FUNCTION: PR_Sync
  996.  * DESCRIPTION:
  997.  *     Sync any buffered data for a fd to its backing device (disk).
  998.  * INPUTS:
  999.  *     PRFileDesc *fd
  1000.  *         Pointer to a PRFileDesc object that refers to a file or
  1001.  *         socket
  1002.  * OUTPUTS:
  1003.  *     None
  1004.  * RETURN: PRStatus
  1005.  *     PR_SUCCESS is returned if the requested access is permitted.
  1006.  *     Otherwise, PR_FAILURE is returned.
  1007.  ************************************************************************
  1008.  */
  1009.  
  1010. NSPR_API(PRStatus)    PR_Sync(PRFileDesc *fd);
  1011.  
  1012. /************************************************************************/
  1013.  
  1014. struct PRDirEntry {
  1015.     const char *name;        /* name of entry, relative to directory name */
  1016. };
  1017.  
  1018. #ifdef MOZ_UNICODE
  1019. struct PRDirEntryUTF16 {
  1020.     const PRUnichar *name;   /* name of entry in UTF16, relative to
  1021.                               * directory name */
  1022. };
  1023. #endif /* MOZ_UNICODE */
  1024.  
  1025. #if !defined(NO_NSPR_10_SUPPORT)
  1026. #define PR_DirName(dirEntry)    (dirEntry->name)
  1027. #endif
  1028.  
  1029. /*
  1030.  *************************************************************************
  1031.  * FUNCTION: PR_OpenDir
  1032.  * DESCRIPTION:
  1033.  *     Open the directory by the given name
  1034.  * INPUTS:
  1035.  *     const char *name
  1036.  *         path name of the directory to be opened
  1037.  * OUTPUTS:
  1038.  *     None
  1039.  * RETURN: PRDir *
  1040.  *     If the directory is sucessfully opened, a PRDir object is
  1041.  *     dynamically allocated and a pointer to it is returned.
  1042.  *     If the directory cannot be opened, a NULL pointer is returned.
  1043.  * MEMORY:
  1044.  *     Upon successful completion, the return value points to
  1045.  *     dynamically allocated memory.
  1046.  *************************************************************************
  1047.  */
  1048.  
  1049. NSPR_API(PRDir*) PR_OpenDir(const char *name);
  1050.  
  1051. #ifdef MOZ_UNICODE
  1052. /*
  1053.  * EXPERIMENTAL: This function may be removed in a future release.
  1054.  */
  1055. NSPR_API(PRDirUTF16*) PR_OpenDirUTF16(const PRUnichar *name);
  1056. #endif /* MOZ_UNICODE */
  1057.  
  1058. /*
  1059.  *************************************************************************
  1060.  * FUNCTION: PR_ReadDir
  1061.  * DESCRIPTION:
  1062.  * INPUTS:
  1063.  *     PRDir *dir
  1064.  *         pointer to a PRDir object that designates an open directory
  1065.  *     PRDirFlags flags
  1066.  *           PR_SKIP_NONE     Do not skip any files
  1067.  *           PR_SKIP_DOT      Skip the directory entry "." that
  1068.  *                            represents the current directory
  1069.  *           PR_SKIP_DOT_DOT  Skip the directory entry ".." that
  1070.  *                            represents the parent directory.
  1071.  *           PR_SKIP_BOTH     Skip both '.' and '..'
  1072.  *           PR_SKIP_HIDDEN   Skip hidden files
  1073.  * OUTPUTS:
  1074.  * RETURN: PRDirEntry*
  1075.  *     Returns a pointer to the next entry in the directory.  Returns
  1076.  *     a NULL pointer upon reaching the end of the directory or when an
  1077.  *     error occurs. The actual reason can be retrieved via PR_GetError().
  1078.  *************************************************************************
  1079.  */
  1080.  
  1081. typedef enum PRDirFlags {
  1082.     PR_SKIP_NONE = 0x0,
  1083.     PR_SKIP_DOT = 0x1,
  1084.     PR_SKIP_DOT_DOT = 0x2,
  1085.     PR_SKIP_BOTH = 0x3,
  1086.     PR_SKIP_HIDDEN = 0x4
  1087. } PRDirFlags;
  1088.  
  1089. NSPR_API(PRDirEntry*) PR_ReadDir(PRDir *dir, PRDirFlags flags);
  1090.  
  1091. #ifdef MOZ_UNICODE
  1092. /*
  1093.  * EXPERIMENTAL: This function may be removed in a future release.
  1094.  */
  1095. NSPR_API(PRDirEntryUTF16*) PR_ReadDirUTF16(PRDirUTF16 *dir, PRDirFlags flags);
  1096. #endif /* MOZ_UNICODE */
  1097.  
  1098. /*
  1099.  *************************************************************************
  1100.  * FUNCTION: PR_CloseDir
  1101.  * DESCRIPTION:
  1102.  *     Close the specified directory.
  1103.  * INPUTS:
  1104.  *     PRDir *dir
  1105.  *        The directory to be closed.
  1106.  * OUTPUTS:
  1107.  *     None
  1108.  * RETURN: PRStatus
  1109.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  1110.  *        a value of PR_FAILURE. The reason for the failure may be re-
  1111.  *        trieved using PR_GetError().
  1112.  *************************************************************************
  1113.  */
  1114.  
  1115. NSPR_API(PRStatus) PR_CloseDir(PRDir *dir);
  1116.  
  1117. #ifdef MOZ_UNICODE
  1118. /*
  1119.  * EXPERIMENTAL: This function may be removed in a future release.
  1120.  */
  1121. NSPR_API(PRStatus) PR_CloseDirUTF16(PRDirUTF16 *dir);
  1122. #endif /* MOZ_UNICODE */
  1123.  
  1124. /*
  1125.  *************************************************************************
  1126.  * FUNCTION: PR_MkDir
  1127.  * DESCRIPTION:
  1128.  *     Create a new directory with the given name and access mode.
  1129.  * INPUTS:
  1130.  *     const char *name
  1131.  *        The name of the directory to be created. All the path components
  1132.  *        up to but not including the leaf component must already exist.
  1133.  *     PRIntn mode
  1134.  *        See 'mode' definiton in PR_Open().
  1135.  * OUTPUTS:
  1136.  *     None
  1137.  * RETURN: PRStatus
  1138.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  1139.  *        a value of PR_FAILURE. The reason for the failure may be re-
  1140.  *        trieved using PR_GetError().
  1141.  *************************************************************************
  1142.  */
  1143.  
  1144. NSPR_API(PRStatus) PR_MkDir(const char *name, PRIntn mode);
  1145.  
  1146. /*
  1147.  *************************************************************************
  1148.  * FUNCTION: PR_MakeDir
  1149.  * DESCRIPTION:
  1150.  *     Create a new directory with the given name and access mode.
  1151.  *     PR_MakeDir has the same prototype as PR_MkDir but implements
  1152.  *     the specified access mode where possible.
  1153.  *************************************************************************
  1154.  */
  1155.  
  1156. NSPR_API(PRStatus) PR_MakeDir(const char *name, PRIntn mode);
  1157.  
  1158. /*
  1159.  *************************************************************************
  1160.  * FUNCTION: PR_RmDir
  1161.  * DESCRIPTION:
  1162.  *     Remove a directory by the given name.
  1163.  * INPUTS:
  1164.  *     const char *name
  1165.  *        The name of the directory to be removed. All the path components
  1166.  *        must already exist. Only the leaf component will be removed.
  1167.  * OUTPUTS:
  1168.  *     None
  1169.  * RETURN: PRStatus
  1170.  *        If successful, will return a status of PR_SUCCESS. Otherwise
  1171.  *        a value of PR_FAILURE. The reason for the failure may be re-
  1172.  *        trieved using PR_GetError().
  1173.  **************************************************************************
  1174.  */
  1175.  
  1176. NSPR_API(PRStatus) PR_RmDir(const char *name);
  1177.  
  1178. /*
  1179.  *************************************************************************
  1180.  * FUNCTION: PR_NewUDPSocket
  1181.  * DESCRIPTION:
  1182.  *     Create a new UDP socket.
  1183.  * INPUTS:
  1184.  *     None
  1185.  * OUTPUTS:
  1186.  *     None
  1187.  * RETURN: PRFileDesc*
  1188.  *     Upon successful completion, PR_NewUDPSocket returns a pointer
  1189.  *     to the PRFileDesc created for the newly opened UDP socket.
  1190.  *     Returns a NULL pointer if the creation of a new UDP socket failed.
  1191.  *
  1192.  **************************************************************************
  1193.  */
  1194.  
  1195. NSPR_API(PRFileDesc*)    PR_NewUDPSocket(void);
  1196.  
  1197. /*
  1198.  *************************************************************************
  1199.  * FUNCTION: PR_NewTCPSocket
  1200.  * DESCRIPTION:
  1201.  *     Create a new TCP socket.
  1202.  * INPUTS:
  1203.  *     None
  1204.  * OUTPUTS:
  1205.  *     None
  1206.  * RETURN: PRFileDesc*
  1207.  *     Upon successful completion, PR_NewTCPSocket returns a pointer
  1208.  *     to the PRFileDesc created for the newly opened TCP socket.
  1209.  *     Returns a NULL pointer if the creation of a new TCP socket failed.
  1210.  *
  1211.  **************************************************************************
  1212.  */
  1213.  
  1214. NSPR_API(PRFileDesc*)    PR_NewTCPSocket(void);
  1215.  
  1216. /*
  1217.  *************************************************************************
  1218.  * FUNCTION: PR_OpenUDPSocket
  1219.  * DESCRIPTION:
  1220.  *     Create a new UDP socket of the specified address family.
  1221.  * INPUTS:
  1222.  *     PRIntn af
  1223.  *       Address family
  1224.  * OUTPUTS:
  1225.  *     None
  1226.  * RETURN: PRFileDesc*
  1227.  *     Upon successful completion, PR_OpenUDPSocket returns a pointer
  1228.  *     to the PRFileDesc created for the newly opened UDP socket.
  1229.  *     Returns a NULL pointer if the creation of a new UDP socket failed.
  1230.  *
  1231.  **************************************************************************
  1232.  */
  1233.  
  1234. NSPR_API(PRFileDesc*)    PR_OpenUDPSocket(PRIntn af);
  1235.  
  1236. /*
  1237.  *************************************************************************
  1238.  * FUNCTION: PR_OpenTCPSocket
  1239.  * DESCRIPTION:
  1240.  *     Create a new TCP socket of the specified address family.
  1241.  * INPUTS:
  1242.  *     PRIntn af
  1243.  *       Address family
  1244.  * OUTPUTS:
  1245.  *     None
  1246.  * RETURN: PRFileDesc*
  1247.  *     Upon successful completion, PR_NewTCPSocket returns a pointer
  1248.  *     to the PRFileDesc created for the newly opened TCP socket.
  1249.  *     Returns a NULL pointer if the creation of a new TCP socket failed.
  1250.  *
  1251.  **************************************************************************
  1252.  */
  1253.  
  1254. NSPR_API(PRFileDesc*)    PR_OpenTCPSocket(PRIntn af);
  1255.  
  1256. /*
  1257.  *************************************************************************
  1258.  * FUNCTION: PR_Connect
  1259.  * DESCRIPTION:
  1260.  *     Initiate a connection on a socket.
  1261.  * INPUTS:
  1262.  *     PRFileDesc *fd
  1263.  *       Points to a PRFileDesc object representing a socket
  1264.  *     PRNetAddr *addr
  1265.  *       Specifies the address of the socket in its own communication
  1266.  *       space.
  1267.  *     PRIntervalTime timeout
  1268.  *       Time limit for completion of the connect operation.
  1269.  * OUTPUTS:
  1270.  *     None
  1271.  * RETURN: PRStatus
  1272.  *     Upon successful completion of connection initiation, PR_Connect
  1273.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1274.  *     failure information can be obtained by calling PR_GetError().
  1275.  **************************************************************************
  1276.  */
  1277.  
  1278. NSPR_API(PRStatus) PR_Connect(
  1279.     PRFileDesc *fd, const PRNetAddr *addr, PRIntervalTime timeout);
  1280.  
  1281. /*
  1282.  *************************************************************************
  1283.  * FUNCTION: PR_ConnectContinue
  1284.  * DESCRIPTION:
  1285.  *     Continue a nonblocking connect.  After a nonblocking connect
  1286.  *     is initiated with PR_Connect() (which fails with
  1287.  *     PR_IN_PROGRESS_ERROR), one should call PR_Poll() on the socket,
  1288.  *     with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.  When
  1289.  *     PR_Poll() returns, one calls PR_ConnectContinue() on the
  1290.  *     socket to determine whether the nonblocking connect has
  1291.  *     completed or is still in progress.  Repeat the PR_Poll(),
  1292.  *     PR_ConnectContinue() sequence until the nonblocking connect
  1293.  *     has completed.
  1294.  * INPUTS:
  1295.  *     PRFileDesc *fd
  1296.  *         the file descriptor representing a socket
  1297.  *     PRInt16 out_flags
  1298.  *         the out_flags field of the poll descriptor returned by
  1299.  *         PR_Poll()
  1300.  * RETURN: PRStatus
  1301.  *     If the nonblocking connect has successfully completed,
  1302.  *     PR_ConnectContinue returns PR_SUCCESS.  If PR_ConnectContinue()
  1303.  *     returns PR_FAILURE, call PR_GetError():
  1304.  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
  1305.  *       progress and has not completed yet.  The caller should poll
  1306.  *       on the file descriptor for the in_flags
  1307.  *       PR_POLL_WRITE|PR_POLL_EXCEPT and retry PR_ConnectContinue
  1308.  *       later when PR_Poll() returns.
  1309.  *     - Other errors: the nonblocking connect has failed with this
  1310.  *       error code.
  1311.  */
  1312.  
  1313. NSPR_API(PRStatus)    PR_ConnectContinue(PRFileDesc *fd, PRInt16 out_flags);
  1314.  
  1315. /*
  1316.  *************************************************************************
  1317.  * THIS FUNCTION IS DEPRECATED.  USE PR_ConnectContinue INSTEAD.
  1318.  *
  1319.  * FUNCTION: PR_GetConnectStatus
  1320.  * DESCRIPTION:
  1321.  *     Get the completion status of a nonblocking connect.  After
  1322.  *     a nonblocking connect is initiated with PR_Connect() (which
  1323.  *     fails with PR_IN_PROGRESS_ERROR), one should call PR_Poll()
  1324.  *     on the socket, with the in_flags PR_POLL_WRITE | PR_POLL_EXCEPT.
  1325.  *     When PR_Poll() returns, one calls PR_GetConnectStatus on the
  1326.  *     PRPollDesc structure to determine whether the nonblocking
  1327.  *     connect has succeeded or failed.
  1328.  * INPUTS:
  1329.  *     const PRPollDesc *pd
  1330.  *         Pointer to a PRPollDesc whose fd member is the socket,
  1331.  *         and in_flags must contain PR_POLL_WRITE and PR_POLL_EXCEPT.
  1332.  *         PR_Poll() should have been called and set the out_flags.
  1333.  * RETURN: PRStatus
  1334.  *     If the nonblocking connect has successfully completed,
  1335.  *     PR_GetConnectStatus returns PR_SUCCESS.  If PR_GetConnectStatus()
  1336.  *     returns PR_FAILURE, call PR_GetError():
  1337.  *     - PR_IN_PROGRESS_ERROR: the nonblocking connect is still in
  1338.  *       progress and has not completed yet.
  1339.  *     - Other errors: the nonblocking connect has failed with this
  1340.  *       error code.
  1341.  */
  1342.  
  1343. NSPR_API(PRStatus)    PR_GetConnectStatus(const PRPollDesc *pd);
  1344.  
  1345. /*
  1346.  *************************************************************************
  1347.  * FUNCTION: PR_Accept
  1348.  * DESCRIPTION:
  1349.  *     Accept a connection on a socket.
  1350.  * INPUTS:
  1351.  *     PRFileDesc *fd
  1352.  *       Points to a PRFileDesc object representing the rendezvous socket
  1353.  *       on which the caller is willing to accept new connections.
  1354.  *     PRIntervalTime timeout
  1355.  *       Time limit for completion of the accept operation.
  1356.  * OUTPUTS:
  1357.  *     PRNetAddr *addr
  1358.  *       Returns the address of the connecting entity in its own
  1359.  *       communication space. It may be NULL.
  1360.  * RETURN: PRFileDesc*
  1361.  *     Upon successful acceptance of a connection, PR_Accept
  1362.  *     returns a valid file descriptor. Otherwise, it returns NULL.
  1363.  *     Further failure information can be obtained by calling PR_GetError().
  1364.  **************************************************************************
  1365.  */
  1366.  
  1367. NSPR_API(PRFileDesc*) PR_Accept(
  1368.     PRFileDesc *fd, PRNetAddr *addr, PRIntervalTime timeout);
  1369.  
  1370. /*
  1371.  *************************************************************************
  1372.  * FUNCTION: PR_Bind
  1373.  * DESCRIPTION:
  1374.  *    Bind an address to a socket.
  1375.  * INPUTS:
  1376.  *     PRFileDesc *fd
  1377.  *       Points to a PRFileDesc object representing a socket.
  1378.  *     PRNetAddr *addr
  1379.  *       Specifies the address to which the socket will be bound.
  1380.  * OUTPUTS:
  1381.  *     None
  1382.  * RETURN: PRStatus
  1383.  *     Upon successful binding of an address to a socket, PR_Bind
  1384.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1385.  *     failure information can be obtained by calling PR_GetError().
  1386.  **************************************************************************
  1387.  */
  1388.  
  1389. NSPR_API(PRStatus) PR_Bind(PRFileDesc *fd, const PRNetAddr *addr);
  1390.  
  1391. /*
  1392.  *************************************************************************
  1393.  * FUNCTION: PR_Listen
  1394.  * DESCRIPTION:
  1395.  *    Listen for connections on a socket.
  1396.  * INPUTS:
  1397.  *     PRFileDesc *fd
  1398.  *       Points to a PRFileDesc object representing a socket that will be
  1399.  *       used to listen for new connections.
  1400.  *     PRIntn backlog
  1401.  *       Specifies the maximum length of the queue of pending connections.
  1402.  * OUTPUTS:
  1403.  *     None
  1404.  * RETURN: PRStatus
  1405.  *     Upon successful completion of listen request, PR_Listen
  1406.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1407.  *     failure information can be obtained by calling PR_GetError().
  1408.  **************************************************************************
  1409.  */
  1410.  
  1411. NSPR_API(PRStatus) PR_Listen(PRFileDesc *fd, PRIntn backlog);
  1412.  
  1413. /*
  1414.  *************************************************************************
  1415.  * FUNCTION: PR_Shutdown
  1416.  * DESCRIPTION:
  1417.  *    Shut down part of a full-duplex connection on a socket.
  1418.  * INPUTS:
  1419.  *     PRFileDesc *fd
  1420.  *       Points to a PRFileDesc object representing a connected socket.
  1421.  *     PRIntn how
  1422.  *       Specifies the kind of disallowed operations on the socket.
  1423.  *           PR_SHUTDOWN_RCV - Further receives will be disallowed
  1424.  *           PR_SHUTDOWN_SEND - Further sends will be disallowed
  1425.  *           PR_SHUTDOWN_BOTH - Further sends and receives will be disallowed
  1426.  * OUTPUTS:
  1427.  *     None
  1428.  * RETURN: PRStatus
  1429.  *     Upon successful completion of shutdown request, PR_Shutdown
  1430.  *     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1431.  *     failure information can be obtained by calling PR_GetError().
  1432.  **************************************************************************
  1433.  */
  1434.  
  1435. typedef enum PRShutdownHow
  1436. {
  1437.     PR_SHUTDOWN_RCV = 0,      /* disallow further receives */
  1438.     PR_SHUTDOWN_SEND = 1,     /* disallow further sends */
  1439.     PR_SHUTDOWN_BOTH = 2      /* disallow further receives and sends */
  1440. } PRShutdownHow;
  1441.  
  1442. NSPR_API(PRStatus)    PR_Shutdown(PRFileDesc *fd, PRShutdownHow how);
  1443.  
  1444. /*
  1445.  *************************************************************************
  1446.  * FUNCTION: PR_Recv
  1447.  * DESCRIPTION:
  1448.  *    Receive a specified number of bytes from a connected socket.
  1449.  *     The operation will block until some positive number of bytes are 
  1450.  *     transferred, a time out has occurred, or there is an error. 
  1451.  *     No more than 'amount' bytes will be transferred.
  1452.  * INPUTS:
  1453.  *     PRFileDesc *fd
  1454.  *       points to a PRFileDesc object representing a socket.
  1455.  *     void *buf
  1456.  *       pointer to a buffer to hold the data received.
  1457.  *     PRInt32 amount
  1458.  *       the size of 'buf' (in bytes)
  1459.  *     PRIntn flags
  1460.  *       must be zero or PR_MSG_PEEK.
  1461.  *     PRIntervalTime timeout
  1462.  *       Time limit for completion of the receive operation.
  1463.  * OUTPUTS:
  1464.  *     None
  1465.  * RETURN: PRInt32
  1466.  *         a positive number indicates the number of bytes actually received.
  1467.  *         0 means the network connection is closed.
  1468.  *         -1 indicates a failure. The reason for the failure is obtained
  1469.  *         by calling PR_GetError().
  1470.  **************************************************************************
  1471.  */
  1472.  
  1473. #define PR_MSG_PEEK 0x2
  1474.  
  1475. NSPR_API(PRInt32)    PR_Recv(PRFileDesc *fd, void *buf, PRInt32 amount,
  1476.                 PRIntn flags, PRIntervalTime timeout);
  1477.  
  1478. /*
  1479.  *************************************************************************
  1480.  * FUNCTION: PR_Send
  1481.  * DESCRIPTION:
  1482.  *    Send a specified number of bytes from a connected socket.
  1483.  *     The operation will block until all bytes are 
  1484.  *     processed, a time out has occurred, or there is an error. 
  1485.  * INPUTS:
  1486.  *     PRFileDesc *fd
  1487.  *       points to a PRFileDesc object representing a socket.
  1488.  *     void *buf
  1489.  *       pointer to a buffer from where the data is sent.
  1490.  *     PRInt32 amount
  1491.  *       the size of 'buf' (in bytes)
  1492.  *     PRIntn flags
  1493.  *        (OBSOLETE - must always be zero)
  1494.  *     PRIntervalTime timeout
  1495.  *       Time limit for completion of the send operation.
  1496.  * OUTPUTS:
  1497.  *     None
  1498.  * RETURN: PRInt32
  1499.  *     A positive number indicates the number of bytes successfully processed.
  1500.  *     This number must always equal 'amount'. A -1 is an indication that the
  1501.  *     operation failed. The reason for the failure is obtained by calling
  1502.  *     PR_GetError().
  1503.  **************************************************************************
  1504.  */
  1505.  
  1506. NSPR_API(PRInt32)    PR_Send(PRFileDesc *fd, const void *buf, PRInt32 amount,
  1507.                                 PRIntn flags, PRIntervalTime timeout);
  1508.  
  1509. /*
  1510.  *************************************************************************
  1511.  * FUNCTION: PR_RecvFrom
  1512.  * DESCRIPTION:
  1513.  *     Receive up to a specified number of bytes from socket which may
  1514.  *     or may not be connected.
  1515.  *     The operation will block until one or more bytes are 
  1516.  *     transferred, a time out has occurred, or there is an error. 
  1517.  *     No more than 'amount' bytes will be transferred.
  1518.  * INPUTS:
  1519.  *     PRFileDesc *fd
  1520.  *       points to a PRFileDesc object representing a socket.
  1521.  *     void *buf
  1522.  *       pointer to a buffer to hold the data received.
  1523.  *     PRInt32 amount
  1524.  *       the size of 'buf' (in bytes)
  1525.  *     PRIntn flags
  1526.  *        (OBSOLETE - must always be zero)
  1527.  *     PRNetAddr *addr
  1528.  *       Specifies the address of the sending peer. It may be NULL.
  1529.  *     PRIntervalTime timeout
  1530.  *       Time limit for completion of the receive operation.
  1531.  * OUTPUTS:
  1532.  *     None
  1533.  * RETURN: PRInt32
  1534.  *         a positive number indicates the number of bytes actually received.
  1535.  *         0 means the network connection is closed.
  1536.  *         -1 indicates a failure. The reason for the failure is obtained
  1537.  *         by calling PR_GetError().
  1538.  **************************************************************************
  1539.  */
  1540.  
  1541. NSPR_API(PRInt32) PR_RecvFrom(
  1542.     PRFileDesc *fd, void *buf, PRInt32 amount, PRIntn flags,
  1543.     PRNetAddr *addr, PRIntervalTime timeout);
  1544.  
  1545. /*
  1546.  *************************************************************************
  1547.  * FUNCTION: PR_SendTo
  1548.  * DESCRIPTION:
  1549.  *    Send a specified number of bytes from an unconnected socket.
  1550.  *    The operation will block until all bytes are 
  1551.  *    sent, a time out has occurred, or there is an error. 
  1552.  * INPUTS:
  1553.  *     PRFileDesc *fd
  1554.  *       points to a PRFileDesc object representing an unconnected socket.
  1555.  *     void *buf
  1556.  *       pointer to a buffer from where the data is sent.
  1557.  *     PRInt32 amount
  1558.  *       the size of 'buf' (in bytes)
  1559.  *     PRIntn flags
  1560.  *        (OBSOLETE - must always be zero)
  1561.  *     PRNetAddr *addr
  1562.  *       Specifies the address of the peer.
  1563. .*     PRIntervalTime timeout
  1564.  *       Time limit for completion of the send operation.
  1565.  * OUTPUTS:
  1566.  *     None
  1567.  * RETURN: PRInt32
  1568.  *     A positive number indicates the number of bytes successfully sent.
  1569.  *     -1 indicates a failure. The reason for the failure is obtained
  1570.  *     by calling PR_GetError().
  1571.  **************************************************************************
  1572.  */
  1573.  
  1574. NSPR_API(PRInt32) PR_SendTo(
  1575.     PRFileDesc *fd, const void *buf, PRInt32 amount, PRIntn flags,
  1576.     const PRNetAddr *addr, PRIntervalTime timeout);
  1577.  
  1578. /*
  1579. *************************************************************************
  1580. ** FUNCTION: PR_TransmitFile
  1581. ** DESCRIPTION:
  1582. **    Transmitfile sends a complete file (sourceFile) across a socket 
  1583. **    (networkSocket).  If headers is non-NULL, the headers will be sent across
  1584. **    the socket prior to sending the file.
  1585. ** 
  1586. **    Optionally, the PR_TRANSMITFILE_CLOSE_SOCKET flag may be passed to
  1587. **    transmitfile.  This flag specifies that transmitfile should close the
  1588. **    socket after sending the data.
  1589. **
  1590. ** INPUTS:
  1591. **    PRFileDesc *networkSocket
  1592. **        The socket to send data over
  1593. **    PRFileDesc *sourceFile
  1594. **        The file to send
  1595. **    const void *headers
  1596. **        A pointer to headers to be sent before sending data
  1597. **    PRInt32       hlen
  1598. **        length of header buffers in bytes.
  1599. **    PRTransmitFileFlags       flags
  1600. **        If the flags indicate that the connection should be closed,
  1601. **        it will be done immediately after transferring the file, unless
  1602. **        the operation is unsuccessful. 
  1603. .*     PRIntervalTime timeout
  1604.  *        Time limit for completion of the transmit operation.
  1605. **
  1606. ** RETURNS:
  1607. **    Returns the number of bytes written or -1 if the operation failed.
  1608. **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
  1609. **    SOCKET flag is ignored. The reason for the failure is obtained
  1610. **    by calling PR_GetError().
  1611. **************************************************************************
  1612. */
  1613.  
  1614. NSPR_API(PRInt32) PR_TransmitFile(
  1615.     PRFileDesc *networkSocket, PRFileDesc *sourceFile,
  1616.     const void *headers, PRInt32 hlen, PRTransmitFileFlags flags,
  1617.     PRIntervalTime timeout);
  1618.  
  1619. /*
  1620. *************************************************************************
  1621. ** FUNCTION: PR_SendFile
  1622. ** DESCRIPTION:
  1623. **    PR_SendFile sends data from a file (sendData->fd) across a socket 
  1624. **    (networkSocket).  If specified, a header and/or trailer buffer are sent
  1625. **      before and after the file, respectively. The file offset, number of bytes
  1626. **       of file data to send, the header and trailer buffers are specified in the
  1627. **      sendData argument.
  1628. ** 
  1629. **    Optionally, if the PR_TRANSMITFILE_CLOSE_SOCKET flag is passed, the
  1630. **    socket is closed after successfully sending the data.
  1631. **
  1632. ** INPUTS:
  1633. **    PRFileDesc *networkSocket
  1634. **        The socket to send data over
  1635. **    PRSendFileData *sendData
  1636. **        Contains the FD, file offset and length, header and trailer
  1637. **          buffer specifications.
  1638. **    PRTransmitFileFlags       flags
  1639. **        If the flags indicate that the connection should be closed,
  1640. **        it will be done immediately after transferring the file, unless
  1641. **        the operation is unsuccessful. 
  1642. .*     PRIntervalTime timeout
  1643.  *        Time limit for completion of the send operation.
  1644. **
  1645. ** RETURNS:
  1646. **    Returns the number of bytes written or -1 if the operation failed.
  1647. **    If an error occurs while sending the file, the PR_TRANSMITFILE_CLOSE_
  1648. **    SOCKET flag is ignored. The reason for the failure is obtained
  1649. **    by calling PR_GetError().
  1650. **************************************************************************
  1651. */
  1652.  
  1653. struct PRSendFileData {
  1654.     PRFileDesc    *fd;            /* file to send                            */
  1655.     PRUint32    file_offset;    /* file offset                            */
  1656.     PRSize        file_nbytes;    /* number of bytes of file data to send    */
  1657.                                 /* if 0, send data from file_offset to    */
  1658.                                 /* end-of-file.                            */
  1659.     const void    *header;        /* header buffer                        */
  1660.     PRInt32        hlen;            /* header len                            */
  1661.     const void    *trailer;        /* trailer buffer                        */
  1662.     PRInt32        tlen;            /* trailer len                            */
  1663. };
  1664.  
  1665.  
  1666. NSPR_API(PRInt32) PR_SendFile(
  1667.     PRFileDesc *networkSocket, PRSendFileData *sendData,
  1668.     PRTransmitFileFlags flags, PRIntervalTime timeout);
  1669.  
  1670. /*
  1671. *************************************************************************
  1672. ** FUNCTION: PR_AcceptRead
  1673. ** DESCRIPTION:
  1674. **    AcceptRead accepts a new connection, returns the newly created
  1675. **    socket's descriptor and also returns the connecting peer's address.
  1676. **    AcceptRead, as its name suggests, also receives the first block of data 
  1677. **    sent by the peer.
  1678. **
  1679. ** INPUTS:
  1680. **    PRFileDesc *listenSock
  1681. **        A socket descriptor that has been called with the PR_Listen() 
  1682. **        function, also known as the rendezvous socket.
  1683. **    void *buf
  1684. **        A pointer to a buffer to receive data sent by the client.  This 
  1685. **        buffer must be large enough to receive <amount> bytes of data
  1686. **        and two PRNetAddr structures, plus an extra 32 bytes. See:
  1687. **        PR_ACCEPT_READ_BUF_OVERHEAD.
  1688. **    PRInt32 amount
  1689. **        The number of bytes of client data to receive.  Does not include
  1690. **        the size of the PRNetAddr structures.  If 0, no data will be read
  1691. **        from the client.
  1692. **    PRIntervalTime timeout
  1693. **        The timeout interval only applies to the read portion of the 
  1694. **        operation.  PR_AcceptRead will block indefinitely until the 
  1695. **        connection is accepted; the read will timeout after the timeout 
  1696. **        interval elapses.
  1697. ** OUTPUTS:
  1698. **    PRFileDesc **acceptedSock
  1699. **        The file descriptor for the newly connected socket.  This parameter
  1700. **        will only be valid if the function return does not indicate failure.
  1701. **    PRNetAddr  **peerAddr,
  1702. **        The address of the remote socket.  This parameter will only be
  1703. **        valid if the function return does not indicate failure.  The
  1704. **        returned address is not guaranteed to be properly aligned.
  1705. ** 
  1706. ** RETURNS:
  1707. **     The number of bytes read from the client or -1 on failure.  The reason 
  1708. **     for the failure is obtained by calling PR_GetError().
  1709. **************************************************************************
  1710. **/       
  1711. /* define buffer overhead constant. Add this value to the user's 
  1712. ** data length when allocating a buffer to accept data.
  1713. **    Example:
  1714. **    #define USER_DATA_SIZE 10
  1715. **    char buf[USER_DATA_SIZE + PR_ACCEPT_READ_BUF_OVERHEAD];
  1716. **    bytesRead = PR_AcceptRead( s, fd, &a, &p, USER_DATA_SIZE, ...);
  1717. */
  1718. #define PR_ACCEPT_READ_BUF_OVERHEAD (32+(2*sizeof(PRNetAddr)))
  1719.  
  1720. NSPR_API(PRInt32) PR_AcceptRead(
  1721.     PRFileDesc *listenSock, PRFileDesc **acceptedSock,
  1722.     PRNetAddr **peerAddr, void *buf, PRInt32 amount, PRIntervalTime timeout);
  1723.  
  1724. /*
  1725. *************************************************************************
  1726. ** FUNCTION: PR_NewTCPSocketPair
  1727. ** DESCRIPTION:
  1728. **    Create a new TCP socket pair. The returned descriptors can be used
  1729. **    interchangeably; they are interconnected full-duplex descriptors: data
  1730. **    written to one can be read from the other and vice-versa.
  1731. **
  1732. ** INPUTS:
  1733. **    None
  1734. ** OUTPUTS:
  1735. **    PRFileDesc *fds[2]
  1736. **        The file descriptor pair for the newly created TCP sockets.
  1737. ** RETURN: PRStatus
  1738. **     Upon successful completion of TCP socket pair, PR_NewTCPSocketPair 
  1739. **     returns PR_SUCCESS.  Otherwise, it returns PR_FAILURE.  Further
  1740. **     failure information can be obtained by calling PR_GetError().
  1741. ** XXX can we implement this on windoze and mac?
  1742. **************************************************************************
  1743. **/
  1744. NSPR_API(PRStatus) PR_NewTCPSocketPair(PRFileDesc *fds[2]);
  1745.  
  1746. /*
  1747. *************************************************************************
  1748. ** FUNCTION: PR_GetSockName
  1749. ** DESCRIPTION:
  1750. **    Get socket name.  Return the network address for this socket.
  1751. **
  1752. ** INPUTS:
  1753. **     PRFileDesc *fd
  1754. **       Points to a PRFileDesc object representing the socket.
  1755. ** OUTPUTS:
  1756. **     PRNetAddr *addr
  1757. **       Returns the address of the socket in its own communication space.
  1758. ** RETURN: PRStatus
  1759. **     Upon successful completion, PR_GetSockName returns PR_SUCCESS.  
  1760. **     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1761. **     be obtained by calling PR_GetError().
  1762. **************************************************************************
  1763. **/
  1764. NSPR_API(PRStatus)    PR_GetSockName(PRFileDesc *fd, PRNetAddr *addr);
  1765.  
  1766. /*
  1767. *************************************************************************
  1768. ** FUNCTION: PR_GetPeerName
  1769. ** DESCRIPTION:
  1770. **    Get name of the connected peer.  Return the network address for the 
  1771. **    connected peer socket.
  1772. **
  1773. ** INPUTS:
  1774. **     PRFileDesc *fd
  1775. **       Points to a PRFileDesc object representing the connected peer.
  1776. ** OUTPUTS:
  1777. **     PRNetAddr *addr
  1778. **       Returns the address of the connected peer in its own communication
  1779. **       space.
  1780. ** RETURN: PRStatus
  1781. **     Upon successful completion, PR_GetPeerName returns PR_SUCCESS.  
  1782. **     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1783. **     be obtained by calling PR_GetError().
  1784. **************************************************************************
  1785. **/
  1786. NSPR_API(PRStatus)    PR_GetPeerName(PRFileDesc *fd, PRNetAddr *addr);
  1787.  
  1788. NSPR_API(PRStatus)    PR_GetSocketOption(
  1789.     PRFileDesc *fd, PRSocketOptionData *data);
  1790.  
  1791. NSPR_API(PRStatus)    PR_SetSocketOption(
  1792.     PRFileDesc *fd, const PRSocketOptionData *data);
  1793.  
  1794. /*
  1795.  *********************************************************************
  1796.  *
  1797.  * File descriptor inheritance
  1798.  *
  1799.  *********************************************************************
  1800.  */
  1801.  
  1802. /*
  1803.  ************************************************************************
  1804.  * FUNCTION: PR_SetFDInheritable
  1805.  * DESCRIPTION:
  1806.  *    Set the inheritance attribute of a file descriptor.
  1807.  *
  1808.  * INPUTS:
  1809.  *     PRFileDesc *fd
  1810.  *       Points to a PRFileDesc object.
  1811.  *     PRBool inheritable
  1812.  *       If PR_TRUE, the file descriptor fd is set to be inheritable
  1813.  *       by a child process.  If PR_FALSE, the file descriptor is set
  1814.  *       to be not inheritable by a child process.
  1815.  * RETURN: PRStatus
  1816.  *     Upon successful completion, PR_SetFDInheritable returns PR_SUCCESS.  
  1817.  *     Otherwise, it returns PR_FAILURE.  Further failure information can 
  1818.  *     be obtained by calling PR_GetError().
  1819.  *************************************************************************
  1820.  */
  1821. NSPR_API(PRStatus) PR_SetFDInheritable(
  1822.     PRFileDesc *fd,
  1823.     PRBool inheritable);
  1824.  
  1825. /*
  1826.  ************************************************************************
  1827.  * FUNCTION: PR_GetInheritedFD
  1828.  * DESCRIPTION:
  1829.  *    Get an inherited file descriptor with the specified name.
  1830.  *
  1831.  * INPUTS:
  1832.  *     const char *name
  1833.  *       The name of the inherited file descriptor.
  1834.  * RETURN: PRFileDesc *
  1835.  *     Upon successful completion, PR_GetInheritedFD returns the
  1836.  *     inherited file descriptor with the specified name.  Otherwise,  
  1837.  *     it returns NULL.  Further failure information can be obtained
  1838.  *     by calling PR_GetError().
  1839.  *************************************************************************
  1840.  */
  1841. NSPR_API(PRFileDesc *) PR_GetInheritedFD(const char *name);
  1842.  
  1843. /*
  1844.  *********************************************************************
  1845.  *
  1846.  * Memory-mapped files
  1847.  *
  1848.  *********************************************************************
  1849.  */
  1850.  
  1851. typedef struct PRFileMap PRFileMap;
  1852.  
  1853. /*
  1854.  * protection options for read and write accesses of a file mapping
  1855.  */
  1856. typedef enum PRFileMapProtect {
  1857.     PR_PROT_READONLY,     /* read only */
  1858.     PR_PROT_READWRITE,    /* readable, and write is shared */
  1859.     PR_PROT_WRITECOPY     /* readable, and write is private (copy-on-write) */
  1860. } PRFileMapProtect;
  1861.  
  1862. NSPR_API(PRFileMap *) PR_CreateFileMap(
  1863.     PRFileDesc *fd,
  1864.     PRInt64 size,
  1865.     PRFileMapProtect prot);
  1866.  
  1867. /*
  1868.  * return the alignment (in bytes) of the offset argument to PR_MemMap
  1869.  */
  1870. NSPR_API(PRInt32) PR_GetMemMapAlignment(void);
  1871.  
  1872. NSPR_API(void *) PR_MemMap(
  1873.     PRFileMap *fmap,
  1874.     PROffset64 offset,  /* must be aligned and sized according to the
  1875.                          * return value of PR_GetMemMapAlignment() */
  1876.     PRUint32 len);
  1877.  
  1878. NSPR_API(PRStatus) PR_MemUnmap(void *addr, PRUint32 len);
  1879.  
  1880. NSPR_API(PRStatus) PR_CloseFileMap(PRFileMap *fmap);
  1881.  
  1882. /*
  1883.  ******************************************************************
  1884.  *
  1885.  * Interprocess communication
  1886.  *
  1887.  ******************************************************************
  1888.  */
  1889.  
  1890. /*
  1891.  * Creates an anonymous pipe and returns file descriptors for the
  1892.  * read and write ends of the pipe.
  1893.  */
  1894.  
  1895. NSPR_API(PRStatus) PR_CreatePipe(
  1896.     PRFileDesc **readPipe,
  1897.     PRFileDesc **writePipe
  1898. );
  1899.  
  1900. /************************************************************************/
  1901. /************** The following definitions are for poll ******************/
  1902. /************************************************************************/
  1903.  
  1904. struct PRPollDesc {
  1905.     PRFileDesc* fd;
  1906.     PRInt16 in_flags;
  1907.     PRInt16 out_flags;
  1908. };
  1909.  
  1910. /*
  1911. ** Bit values for PRPollDesc.in_flags or PRPollDesc.out_flags. Binary-or
  1912. ** these together to produce the desired poll request.
  1913. */
  1914.  
  1915. #if defined(_PR_POLL_BACKCOMPAT)
  1916.  
  1917. #include <poll.h>
  1918. #define PR_POLL_READ    POLLIN
  1919. #define PR_POLL_WRITE   POLLOUT
  1920. #define PR_POLL_EXCEPT  POLLPRI
  1921. #define PR_POLL_ERR     POLLERR     /* only in out_flags */
  1922. #define PR_POLL_NVAL    POLLNVAL    /* only in out_flags when fd is bad */
  1923. #define PR_POLL_HUP     POLLHUP     /* only in out_flags */
  1924.  
  1925. #else  /* _PR_POLL_BACKCOMPAT */
  1926.  
  1927. #define PR_POLL_READ    0x1
  1928. #define PR_POLL_WRITE   0x2
  1929. #define PR_POLL_EXCEPT  0x4
  1930. #define PR_POLL_ERR     0x8         /* only in out_flags */
  1931. #define PR_POLL_NVAL    0x10        /* only in out_flags when fd is bad */
  1932. #define PR_POLL_HUP     0x20        /* only in out_flags */
  1933.  
  1934. #endif  /* _PR_POLL_BACKCOMPAT */
  1935.  
  1936. /*
  1937. *************************************************************************
  1938. ** FUNCTION:    PR_Poll
  1939. ** DESCRIPTION:
  1940. **
  1941. ** The call returns as soon as I/O is ready on one or more of the underlying
  1942. ** socket objects. A count of the number of ready descriptors is
  1943. ** returned unless a timeout occurs in which case zero is returned.
  1944. **
  1945. ** PRPollDesc.fd should be set to a pointer to a PRFileDesc object
  1946. ** representing a socket. This field can be set to NULL to indicate to
  1947. ** PR_Poll that this PRFileDesc object should be ignored.
  1948. ** PRPollDesc.in_flags should be set to the desired request
  1949. ** (read/write/except or some combination). Upon successful return from
  1950. ** this call PRPollDesc.out_flags will be set to indicate what kind of
  1951. ** i/o can be performed on the respective descriptor. PR_Poll() uses the
  1952. ** out_flags fields as scratch variables during the call. If PR_Poll()
  1953. ** returns 0 or -1, the out_flags fields do not contain meaningful values
  1954. ** and must not be used.
  1955. **
  1956. ** INPUTS:
  1957. **      PRPollDesc *pds         A pointer to an array of PRPollDesc
  1958. **
  1959. **      PRIntn npds             The number of elements in the array
  1960. **                              If this argument is zero PR_Poll is
  1961. **                              equivalent to a PR_Sleep(timeout).
  1962. **
  1963. **      PRIntervalTime timeout  Amount of time the call will block waiting
  1964. **                              for I/O to become ready. If this time expires
  1965. **                              w/o any I/O becoming ready, the result will
  1966. **                              be zero.
  1967. **
  1968. ** OUTPUTS:    None
  1969. ** RETURN:
  1970. **      PRInt32                 Number of PRPollDesc's with events or zero
  1971. **                              if the function timed out or -1 on failure.
  1972. **                              The reason for the failure is obtained by
  1973. **                              calling PR_GetError().
  1974. **************************************************************************
  1975. */
  1976. NSPR_API(PRInt32) PR_Poll(
  1977.     PRPollDesc *pds, PRIntn npds, PRIntervalTime timeout);
  1978.  
  1979. /*
  1980. **************************************************************************
  1981. **
  1982. ** Pollable events
  1983. **
  1984. ** A pollable event is a special kind of file descriptor.
  1985. ** The only I/O operation you can perform on a pollable event
  1986. ** is to poll it with the PR_POLL_READ flag.  You can't
  1987. ** read from or write to a pollable event.
  1988. **
  1989. ** The purpose of a pollable event is to combine event waiting
  1990. ** with I/O waiting in a single PR_Poll call.  Pollable events
  1991. ** are implemented using a pipe or a pair of TCP sockets
  1992. ** connected via the loopback address, therefore setting and
  1993. ** waiting for pollable events are expensive operating system
  1994. ** calls.  Do not use pollable events for general thread
  1995. ** synchronization. Use condition variables instead.
  1996. **
  1997. ** A pollable event has two states: set and unset.  Events
  1998. ** are not queued, so there is no notion of an event count.
  1999. ** A pollable event is either set or unset.
  2000. **
  2001. ** A new pollable event is created by a PR_NewPollableEvent
  2002. ** call and is initially in the unset state.
  2003. **
  2004. ** PR_WaitForPollableEvent blocks the calling thread until
  2005. ** the pollable event is set, and then it atomically unsets
  2006. ** the pollable event before it returns.
  2007. **
  2008. ** To set a pollable event, call PR_SetPollableEvent.
  2009. **
  2010. ** One can call PR_Poll with the PR_POLL_READ flag on a pollable
  2011. ** event.  When the pollable event is set, PR_Poll returns with
  2012. ** the PR_POLL_READ flag set in the out_flags.
  2013. **
  2014. ** To close a pollable event, call PR_DestroyPollableEvent
  2015. ** (not PR_Close).
  2016. **
  2017. **************************************************************************
  2018. */
  2019.  
  2020. NSPR_API(PRFileDesc *) PR_NewPollableEvent(void);
  2021.  
  2022. NSPR_API(PRStatus) PR_DestroyPollableEvent(PRFileDesc *event);
  2023.  
  2024. NSPR_API(PRStatus) PR_SetPollableEvent(PRFileDesc *event);
  2025.  
  2026. NSPR_API(PRStatus) PR_WaitForPollableEvent(PRFileDesc *event);
  2027.  
  2028. PR_END_EXTERN_C
  2029.  
  2030. #endif /* prio_h___ */
  2031.